{ "openapi": "3.0.0", "info": { "title": "VTEX Headless CMS", "description": "The [VTEX Headless CMS](https://www.faststore.dev/docs/headless-cms-overview) is a solution for storefront content management.\nYou can use the Headless CMS API to fetch data about your project's pages and content types, including `status`, `id`, and `type`. \r\n\r\n ## Index \r\n\r\n ### Pages \r\n- `GET` [Get all Content Types](https://developers.vtex.com/docs/api-reference/headless-cms-api#get-/_v/cms/api/-projectId-)\r\n- `GET` [Get all CMS pages by content type](https://developers.vtex.com/docs/api-reference/headless-cms-api#get-/_v/cms/api/-projectId-/-content-type-)\r\n- `GET` [Get CMS page](https://developers.vtex.com/docs/api-reference/headless-cms-api#get-/_v/cms/api/-projectId-/-content-type-/-document-id-)\n\n**Servers**\n- `https://{accountName}.myvtex.com/`\n- `https://{workspace}--{accountName}.myvtex.com/`\r\n\r\n## Common parameters\r\n\r\n| **Parameter name** | **Description** | **Type** |\r\n| --------------- | ----------------- | ----------------- |\r\n| {{accountName}} | Name of the VTEX account. Used as part of the URL. | Server variable. |\r\n| {{workspace}} | Name of the VTEX workspace. | Server variable. |\r\n| {{projectId}} | Project ID specified in the settings of the CMS (alpha) app. | Path variable. |\r\n\r\n", "version": "0.31.2" }, "servers": [ { "url": "https://{accountName}.myvtex.com", "variables": { "accountName": { "default": "storeframework", "description": "Name of the VTEX account. Used as part of the URL." } } }, { "url": "https://{workspace}--{accountName}.myvtex.com", "variables": { "accountName": { "default": "storeframework", "description": "Name of the VTEX account. Used as part of the URL." }, "workspace": { "default": "test", "description": "Name of the VTEX workspace. Used as part of the URL." } } } ], "paths": { "/_v/cms/api/{projectId}": { "get": { "summary": "Get all content types", "tags": ["Pages"], "description": "Retrieves data from all Content Types.\r\n\r\n## Permissions\n\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\n\n| **Product** | **Category** | **Resource** |\n| --------------- | ----------------- | ----------------- |\n| CMS | cms | **See CMS menu on the top-bar** |\n| CMS | cms | **Settings** |\n| CMS | GraphQL | **CMS GraphQL API** | \n\n There are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add the resources above to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "GetAllContentTypes", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID specified in the settings of the CMS (alpha) app.", "required": true, "style": "simple", "schema": { "type": "string", "example": "faststore" } } ], "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "description": "Response body object.", "type": "object", "properties": { "contentTypes": { "description": "Array with data of each content type.", "type": "array", "items": { "description": "Object with data of a specific content type.", "type": "object", "properties": { "id": { "description": "Content type identifier specified in the FastStore project.", "type": "string" }, "name": { "description": "Content type name specified in the FastStore project.", "type": "string" }, "configurationSchemaSets": { "description": "Array with data of the `configurationSchemaSets` tabs specified in the FastStore project.", "type": "array", "items": { "description": "Object with data about a specific content type tab.", "type": "object", "properties": { "name": { "description": "Name of the content type tab.", "type": "string" }, "configurations": { "description": "Custom configurations of the content type tab, which may vary based on the content type schema defined in the FastStore project.", "type": "array", "items": { "type": "object", "description": "Object with custom configurations of the content type tab.", "properties": { "name": { "description": "Section of a form.", "type": "string" }, "schema": { "type": "object", "description": "Customizable [JSON schema](https://json-schema.org/learn/getting-started-step-by-step).", "required": [ "title", "description" ], "properties": { "title": { "type": "string", "description": "Section title." }, "description": { "type": "string", "description": "Section description." }, "widget": { "type": "object", "description": "[Widget](https://v1.faststore.dev/tutorials/cms-storecomponents/3#using-widgets) to be used in the UI. Should be filled with [`uiSchema`](https://react-jsonschema-form.readthedocs.io/en/docs/api-reference/uiSchema/) along with [`widgets`](https://react-jsonschema-form.readthedocs.io/en/docs/usage/widgets/) to specify which UI widget should be used to render a given field of your schema. The format should be `\"{uiSchema}\": \"{widgetName}\"`.", "additionalProperties": true } }, "additionalProperties": true } } } } } } } } } } } }, "example": { "contentTypes": [ { "id": "home", "name": "Home Page", "configurationSchemaSets": [] }, { "id": "plp", "name": "PLP", "configurationSchemaSets": [ { "name": "Parameters", "configurations": [ { "name": "Collection", "schema": { "title": "Collection", "description": "Definition of a Collection for the CMS.", "oneOf": [ { "title": "Category", "description": "Configure a Category.", "type": "object", "required": [ "categoryId", "sort" ], "properties": { "categoryId": { "title": "Category ID", "description": "Category identifier to organize the store's products.", "type": "string" }, "sort": { "title": "Default ordering", "description": "Organizes and displays a set of products based on filters.", "type": "string", "default": "\"\"", "enum": [ "\"\"", "discount:desc", "release:desc", "name:asc", "name:desc", "orders:desc", "price:asc", "price:desc" ], "enumNames": [ "Relevance", "Discount", "Release date", "Name, ascending", "Name, descending", "Sales", "Price: Low to High", "Price: High to Low" ] } } }, { "title": "Brand", "description": "Configure a brand page.", "type": "object", "required": [ "brandId", "sort" ], "properties": { "brandId": { "title": "Brand ID", "description": "Brand identifier to categorize a group of products.", "type": "string" }, "sort": { "title": "Default ordering", "description": "Organizes and displays a set of products based on filters.", "type": "string", "enum": [ "\"\"", "discount:desc", "release:desc", "name:asc", "name:desc", "orders:desc", "price:asc", "price:desc" ], "enumNames": [ "Relevance", "Discount", "Release date", "Name, ascending", "Name, descending", "Sales", "Price: Low to High", "Price: High to Low" ] } } }, { "title": "Collection", "description": "Configure a collection page.", "type": "object", "required": [ "clusterId", "sort", "seo" ], "properties": { "clusterId": { "title": "Collection ID", "description": "Collection identifier to categorize a group of products.", "type": "string" }, "sort": { "title": "Default ordering", "description": "Organizes and displays a set of products based on filters.", "type": "string", "default": "\"\"", "enum": [ "\"\"", "discount:desc", "release:desc", "name:asc", "name:desc", "orders:desc", "price:asc", "price:desc" ], "enumNames": [ "Relevance", "Discount", "Release date", "Name, ascending", "Name, descending", "Sales", "Price: Low to High", "Price: High to Low" ] }, "seo": { "type": "object", "title": "Seo", "description": "Search Engine Optimization options.", "widget": { "ui:ObjectFieldTemplate": "GoogleSeoPreview" }, "required": [ "title", "description", "slug" ], "properties": { "title": { "type": "string", "title": "Title", "description": "Title that appears in the browser tab and is suggested for search engines.", "default": "Page title" }, "slug": { "type": "string", "title": "URL slug", "description": "Final part of the page's address. No spaces allowed.", "default": "/path/to/page", "pattern": "^/([a-zA-Z0-9]|-|/|_)*" }, "description": { "type": "string", "title": "Description (Meta description)", "description": "Suggested meta description for search engines.", "default": "Page description" } } } } } ] } } ] } ] }, { "id": "institutionalPage", "name": "Institutional page", "configurationSchemaSets": [ { "name": "SEO", "configurations": [ { "name": "siteMetadataWithSlug", "schema": { "title": "Site Metadata", "description": "Configure global site metadata.", "type": "object", "widget": { "ui:ObjectFieldTemplate": "GoogleSeoPreview" }, "properties": { "title": { "title": "Default page title", "description": "Display this title when no other title is available.", "type": "string", "default": "Store Theme | VTEX FastStore" }, "description": { "title": "Meta tag description", "description": "Meta tag description. A HTML tag that provides a concise summary of a web page.", "type": "string", "default": "A beautifully designed site for general VTEX stores." }, "titleTemplate": { "title": "Title template", "description": "Title template to be used in category/product pages.", "type": "string", "default": "%s | Store Theme" }, "slug": { "title": "URL Slug", "description": "Part of the URL to identify a particular page or product.", "type": "string", "default": "/landing-page-url" } } } } ] } ] } ] } } } }, "404": { "description": "Not Found", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "description": "Response body object.", "properties": { "code": { "type": "string", "description": "Error type code." }, "message": { "type": "string", "description": "Error message." }, "source": { "type": "string", "description": "Error source." }, "requestId": { "type": "string", "description": "VTEX request identifier." } } }, "example": { "code": "NotFound", "message": "storeframework.myvtex.com.br not found", "source": "Vtex.Kube.Router.WebApi", "requestId": "b49522afa7c94b76885450f652be7bfc" } } } }, "500": { "description": "Internal Server Error", "headers": {}, "content": {} } }, "deprecated": false } }, "/_v/cms/api/{projectId}/{content-type}": { "get": { "summary": "Get all CMS pages by content type", "tags": ["Pages"], "description": "Gets data from all pages of a given content type.\r\n\r\n## Permissions\n\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\n\n| **Product** | **Category** | **Resource** |\n| --------------- | ----------------- | ----------------- |\n| CMS | cms | **See CMS menu on the top-bar** |\n| CMS | cms | **Settings** |\n| CMS | GraphQL | **CMS GraphQL API** | \n\n There are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add the resources above to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "GetPagesbyContentType", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID specified in the settings of the CMS (alpha) app.", "required": true, "style": "simple", "schema": { "type": "string", "example": "faststore" } }, { "name": "content-type", "in": "path", "description": "Content type identifier defined in the FastStore project.", "required": true, "style": "simple", "schema": { "type": "string", "example": "plp" } }, { "name": "versionId", "in": "query", "description": "Version ID presented in the URL path of a CMS preview.", "style": "form", "explode": true, "schema": { "type": "string", "example": "e7263fc8-bc68-4052-9e25-dd5a2572d3bb" } }, { "name": "releaseId", "in": "query", "description": "Release ID presented in the URL path of a CMS preview.", "style": "form", "explode": true, "schema": { "type": "string", "example": "6196c277c6dce15f9709a2a7" } }, { "name": "filters[{field}]", "in": "query", "description": "Filter results by a property of the page (e.g., `filters[status]`) or by a nested custom field of the `parameters` object (e.g., `filters[parameters.collection.sort]`).\n*Replace {field} with the desired property.*", "style": "form", "explode": true, "schema": { "type": "string", "example": "published" } } ], "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "hasNextPage": { "description": "Indicates if there are more items to fetch.", "type": "boolean" }, "totalItems": { "description": "Total number of results.", "type": "integer" }, "data": { "description": "Array with data from all pages of the given content type.", "type": "array", "items": { "description": "Object with data from a specific page.", "type": "object", "properties": { "id": { "description": "Document ID presented in the URL path of a CMS preview.", "type": "string" }, "name": { "description": "Name of the page created via the CMS interface.", "type": "string" }, "type": { "description": "Name of the content type defined in the FastStore project.", "type": "string" }, "status": { "description": "Current status of the page.", "type": "string" }, "versionId": { "description": "Version ID.", "type": "string" }, "versionStatus": { "description": "Version status.", "type": "string" }, "sections": { "description": "Sections that compose the page.", "type": "array", "items": { "description": "Object with data about a specific section.", "type": "object", "properties": { "id": { "description": "Section ID.", "type": "string" }, "name": { "description": "Section name.", "type": "string" }, "data": { "description": "Custom field values of the Section. Varies depending on the Section schema defined in the FastStore project.", "type": "object" } } } }, "parameters": { "description": "Object with the configuration values of a `configurationSchemaSets` tab. Varies depending on the content type schema defined in the FastStore project.", "type": "object" } } } } } }, "example": { "hasNextPage": false, "totalItems": 2, "data": [ { "id": "d05d3db8-62b2-4f0b-9b70-d6d25ff29b6e", "name": "Electronics", "type": "plp", "status": "published", "versionId": "ed51d1cd-e020-4f16-b48b-ca83e720472d", "versionStatus": "published", "sections": [ { "id": "1632244409269", "name": "RichText", "data": { "content": "{\"blocks\":[{\"key\":\"dtg7g\",\"text\":\"-\",\"type\":\"unstyled\",\"depth\":0,\"inlineStyleRanges\":[],\"entityRanges\":[],\"data\":{}}],\"entityMap\":{}}" } }, { "id": "1632244445091", "name": "RichText", "data": { "content": "{\"blocks\":[{\"key\":\"2qtft\",\"text\":\",\",\"type\":\"unstyled\",\"depth\":0,\"inlineStyleRanges\":[],\"entityRanges\":[],\"data\":{}}],\"entityMap\":{}}" } } ], "parameters": { "collection": { "sort": "\"\"", "brandId": "123" } } }, { "id": "4ab6388d-79e6-492f-adda-3e251b85eeb6", "name": "Beauty", "type": "plp", "status": "published", "versionId": "95f940d4-584e-4b3d-9872-8c713ba42583", "versionStatus": "published", "sections": [ { "id": "1643319987751", "name": "SearchBanner", "data": { "desktop": { "srcSet": "https://storecomponents.vtexassets.com/assets/vtex.file-manager-graphql/images/dda7c17e-5182-4439-b5af-94f651e2d835___1ef09be73ec9e80c719da13432666441.jpeg" }, "mobile": { "srcSet": "https://storecomponents.vtexassets.com/assets/vtex.file-manager-graphql/images/ed8ef334-c1e5-4269-8728-34dbffeda424___1ef09be73ec9e80c719da13432666441.jpeg" }, "title": "beauty", "description": "beauty products", "alt": "beauty" } } ], "parameters": { "collection": { "sort": "\"\"", "seo": { "title": "Page title", "slug": "/beauty", "description": "beauty products" }, "clusterId": "1182" } } } ] } } } }, "404": { "description": "Not Found", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "description": "Response body object.", "properties": { "code": { "type": "string", "description": "Error type code." }, "message": { "type": "string", "description": "Error message." }, "source": { "type": "string", "description": "Error source." }, "requestId": { "type": "string", "description": "VTEX request identifier." } } }, "example": { "code": "NotFound", "message": "storeframework.myvtex.com.br not found", "source": "Vtex.Kube.Router.WebApi", "requestId": "b49522afa7c94b76885450f652be7bfc" } } } }, "500": { "description": "Internal Server Error", "headers": {}, "content": {} } }, "deprecated": false } }, "/_v/cms/api/{projectId}/{content-type}/{document-id}": { "get": { "summary": "Get CMS page", "tags": ["Pages"], "description": "Gets all data from a given page.\r\n\r\n## Permissions\n\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\n\n| **Product** | **Category** | **Resource** |\n| --------------- | ----------------- | ----------------- |\n| CMS | cms | **See CMS menu on the top-bar** |\n| CMS | cms | **Settings** |\n| CMS | GraphQL | **CMS GraphQL API** | \n\n There are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add the resources above to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "GetCMSpage", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID specified in the settings of the CMS (alpha) app.", "required": true, "style": "simple", "schema": { "type": "string", "example": "faststore" } }, { "name": "content-type", "in": "path", "description": "Content type ID defined in the FastStore project.", "required": true, "style": "simple", "schema": { "type": "string", "example": "plp" } }, { "name": "document-id", "in": "path", "description": "Document ID presented in the URL path of a CMS preview.", "required": true, "style": "simple", "schema": { "type": "string", "example": "5af643b5-9a6d-48f2-9b34-919dd762c908" } }, { "name": "versionId", "in": "query", "description": "Version ID presented in the URL path of a CMS preview.", "style": "form", "explode": true, "schema": { "type": "string", "example": "e7263fc8-bc68-4052-9e25-dd5a2572d3bb" } }, { "name": "releaseId", "in": "query", "description": "Release ID presented in the URL path of a CMS preview.", "style": "form", "explode": true, "schema": { "type": "string", "example": "6196c277c6dce15f9709a2a7" } } ], "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "example": { "id": "ad2fd81d-a53c-4281-8d01-a4fc2f274db3", "name": "Home", "type": "home", "status": "published", "versionId": "e3867e2c-7082-4fe6-83ed-c473242b6970", "versionStatus": "publishing", "sections": [ { "id": "1651804180614", "name": "Alert", "data": { "dismissible": true, "icon": "Bell", "text": "alert text", "linkText": "alert link", "actionLink": "link.url.com" } }, { "id": "1647286556072", "name": "Hero", "data": { "imageSrc": "https://storeframework.vtexassets.com/assets/vtex.file-manager-graphql/images/299f7d32-bb6a-40fd-82a0-4af5573ba572___17239443c00c1e894cff10ca05018058.jpg", "title": "New Products Available", "subtitle": "At FastStore you can shop the best tech of 2022. Enjoy and get 10% off on your first purchase.", "linkText": "See all", "link": "/office", "imageAlt": "hero image" } }, { "id": "1649293076336", "name": "ProductShelf", "data": { "first": 5, "after": "0", "sort": "score_desc", "selectedFacets": [ { "key": "productClusterIds", "value": "140" } ], "title": "Most Wanted!" } }, { "id": "1649293548351", "name": "ProductTiles", "data": { "first": 3, "after": "0", "sort": "score_desc", "selectedFacets": [ { "key": "productClusterIds", "value": "141" } ], "title": "Just Arrived" } }, { "id": "1647286735093", "name": "BannerText", "data": { "title": "Receive our news and promotions in advance.", "caption": "Enjoy and get 10% off on your first purchase!!", "actionPath": "/office", "actionLabel": "See all" } }, { "id": "1649293131632", "name": "ProductShelf", "data": { "first": 5, "after": "0", "sort": "score_desc", "selectedFacets": [ { "key": "productClusterIds", "value": "142" } ], "title": "Deals & Promotions" } } ] }, "schema": { "description": "Object containing the data related to a specific page.", "type": "object", "required": [ "id", "name", "type", "status" ], "properties": { "id": { "description": "Document ID.", "type": "string" }, "name": { "description": "Name of the page created in the CMS app.", "type": "string" }, "type": { "description": "Name of the content type defined in the FastStore project.", "type": "string" }, "status": { "description": "Current status of the page.", "type": "string" }, "versionId": { "description": "Version ID.", "type": "string" }, "versionStatus": { "description": "Version status.", "type": "string" }, "sections": { "description": "Sections that compose the page.", "type": "array", "items": { "description": "Object with data about a specific section.", "type": "object", "required": [ "id", "name", "data" ], "properties": { "id": { "description": "Section ID.", "type": "string" }, "name": { "description": "Section name.", "type": "string" }, "data": { "description": "Content of the Section. Varies depending on the Section schema defined in the FastStore project.", "type": "object" } } } } } } } } }, "404": { "description": "Not Found", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "description": "Response body object.", "properties": { "code": { "type": "string", "description": "Error type code." }, "message": { "type": "string", "description": "Error message." }, "source": { "type": "string", "description": "Error source." }, "requestId": { "type": "string", "description": "VTEX request identifier." } } }, "example": { "code": "NotFound", "message": "storeframework.myvtex.com.br not found", "source": "Vtex.Kube.Router.WebApi", "requestId": "b49522afa7c94b76885450f652be7bfc" } } } }, "500": { "description": "Internal Server Error", "headers": {}, "content": {} } }, "deprecated": false } } }, "tags": [ { "name": "Pages" } ] }